json_archive/

write_strategy.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
//

//! Write strategy for archive operations.
//!
//! There are exactly two questions:
//!   1. Where do we write? (dest_path)
//!   2. Can we write there directly, or do we need to dance?
//!
//! The dance (temp file + atomic swap) is required when:
//!   - source_path == dest_path, AND
//!   - the file is compressed
//!
//! Why? Compressed streams don't support append. To add one
//! record to a gzip file, you decompress everything, add the
//! record, recompress everything. If you write to the same
//! file you're reading, you corrupt it mid-operation.
//!
//! So: write to temp, swap when done. See atomic_file.rs.
//!
//! When source != dest, there is no conflict. Read from source,
//! write to dest. Even if source is compressed. Even if dest
//! is compressed. Even if they use different compression.
//! The source is never modified.
//!
//! When source == dest AND uncompressed, just append. Seek to
//! end, write new records. Simple.
//!
//! The output compression format is determined by dest_path's
//! extension, not the source's format. That's a separate concern.
//!
//! ## Truth Table
//!
//! ```text
//! INPUTS                    OUTPUT FLAG         STRATEGY
//! ───────────────────────────────────────────────────────────────
//! [A.json, B.json]          (none)              Create { out: A.json.archive, fmt: None }
//! [A.json, B.json]          -o X.archive.gz     Create { out: X.archive.gz, fmt: Gzip }
//!
//! [A.archive, B.json]       (none)              Append { path: A.archive }
//! [A.archive, B.json]       -o X.archive        Direct { in: A.archive/None, out: X.archive/None }
//!
//! [A.archive.gz, B.json]    (none)              AtomicSwap { path: A.archive.gz, fmt: Gzip, temp: .A.archive.gz.xxx }
//! [A.archive.gz, B.json]    -o A.archive.gz     AtomicSwap { path: A.archive.gz, fmt: Gzip, temp: .A.archive.gz.xxx }
//! [A.archive.gz, B.json]    -o X.archive        Direct { in: A.archive.gz/Gzip, out: X.archive/None }
//! [A.archive.gz, B.json]    -o X.archive.br     Direct { in: A.archive.gz/Gzip, out: X.archive.br/Brotli }
//! ```
//!
//! The rule:
//! ```text
//! if creating new archive:
//!     Create
//! else if source != dest:
//!     Direct (read from source, write to dest, transcoding as needed)
//! else if source == dest AND uncompressed:
//!     Append (seek to end, write)
//! else if source == dest AND compressed:
//!     AtomicSwap (read all, write to temp, swap)
//! ```

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

use crate::atomic_file::generate_temp_filename;
use crate::detection::CompressionFormat;

/// A path with its compression format.
pub type CompressedPath = (PathBuf, CompressionFormat);

/// Describes how to write archive data based on input/output paths and compression.
#[derive(Debug, Clone)]
pub enum WriteStrategy {
    /// Create a new archive from scratch. No existing archive to read.
    Create { output: CompressedPath },

    /// Append to an existing uncompressed archive in-place.
    /// Just seek to end and write new records.
    Append { path: PathBuf },

    /// Read from one location, write to another.
    /// Handles transcoding between compression formats.
    CopyOnWrite {
        input: CompressedPath,
        output: CompressedPath,
    },

    /// Read compressed archive, write to temp, atomic swap.
    /// Required when source == dest AND compressed.
    AtomicSwap {
        /// The archive path (both input and output)
        path: PathBuf,
        /// Compression format (same for input and output in this case)
        compression: CompressionFormat,
        /// Temp file to write to before swapping
        temp_path: PathBuf,
    },
}

/// Determine compression format from file extension.
///
/// Returns `CompressionFormat::None` for uncompressed files.
pub fn compression_from_extension(path: &Path) -> CompressionFormat {
    let s = path.to_string_lossy();
    if s.ends_with(".gz") {
        CompressionFormat::Gzip
    } else if s.ends_with(".br") {
        CompressionFormat::Brotli
    } else if s.ends_with(".zst") {
        CompressionFormat::Zstd
    } else if s.ends_with(".zlib") {
        CompressionFormat::Zlib
    } else {
        CompressionFormat::None
    }
}

/// Determine write strategy from parsed arguments.
///
/// # Arguments
///
/// * `source_archive` - Path to existing archive if appending, None if creating new
/// * `dest_path` - Where to write the output
/// * `source_compression` - Compression format of source (from magic bytes). Pass
///   `CompressionFormat::None` if unknown or uncompressed.
///
/// # Returns
///
/// The appropriate `WriteStrategy` for this operation.
pub fn determine_strategy(
    source_archive: Option<&Path>,
    dest_path: &Path,
    source_compression: CompressionFormat,
) -> WriteStrategy {
    let dest_compression = compression_from_extension(dest_path);

    // No source archive? Creating new.
    let Some(source) = source_archive else {
        return WriteStrategy::Create {
            output: (dest_path.to_path_buf(), dest_compression),
        };
    };

    // Check if source and dest are the same file
    let same_file = match (source.canonicalize(), dest_path.canonicalize()) {
        (Ok(s), Ok(d)) => s == d,
        // dest doesn't exist yet, or other error - not same file
        _ => false,
    };

    if !same_file {
        // Different files: read from source, write to dest
        let source_fmt = if source_compression == CompressionFormat::None {
            compression_from_extension(source)
        } else {
            source_compression
        };
        return WriteStrategy::CopyOnWrite {
            input: (source.to_path_buf(), source_fmt),
            output: (dest_path.to_path_buf(), dest_compression),
        };
    }

    // Same file - check if compressed
    let compression = if source_compression == CompressionFormat::None {
        compression_from_extension(source)
    } else {
        source_compression
    };

    match compression {
        CompressionFormat::None => {
            // Uncompressed: can append in-place
            WriteStrategy::Append {
                path: dest_path.to_path_buf(),
            }
        }
        fmt => {
            // Compressed: need atomic swap
            WriteStrategy::AtomicSwap {
                path: dest_path.to_path_buf(),
                compression: fmt,
                temp_path: generate_temp_filename(dest_path),
            }
        }
    }
}

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

    #[test]
    fn test_compression_from_extension() {
        assert_eq!(
            compression_from_extension(Path::new("foo.json.archive.gz")),
            CompressionFormat::Gzip
        );
        assert_eq!(
            compression_from_extension(Path::new("foo.json.archive.br")),
            CompressionFormat::Brotli
        );
        assert_eq!(
            compression_from_extension(Path::new("foo.json.archive.zst")),
            CompressionFormat::Zstd
        );
        assert_eq!(
            compression_from_extension(Path::new("foo.json.archive.zlib")),
            CompressionFormat::Zlib
        );
        assert_eq!(
            compression_from_extension(Path::new("foo.json.archive")),
            CompressionFormat::None
        );
        assert_eq!(
            compression_from_extension(Path::new("foo.json")),
            CompressionFormat::None
        );
    }

    #[test]
    fn test_create_new_archive() {
        let dest = Path::new("/tmp/new.json.archive");
        let strategy = determine_strategy(None, dest, CompressionFormat::None);

        match strategy {
            WriteStrategy::Create { output } => {
                assert_eq!(output.0, PathBuf::from("/tmp/new.json.archive"));
                assert_eq!(output.1, CompressionFormat::None);
            }
            _ => panic!("Expected Create strategy"),
        }
    }

    #[test]
    fn test_create_new_compressed_archive() {
        let dest = Path::new("/tmp/new.json.archive.gz");
        let strategy = determine_strategy(None, dest, CompressionFormat::None);

        match strategy {
            WriteStrategy::Create { output } => {
                assert_eq!(output.0, PathBuf::from("/tmp/new.json.archive.gz"));
                assert_eq!(output.1, CompressionFormat::Gzip);
            }
            _ => panic!("Expected Create strategy"),
        }
    }

    #[test]
    fn test_append_uncompressed_same_file() -> Result<(), Box<dyn std::error::Error>> {
        let mut temp = NamedTempFile::with_suffix(".json.archive")?;
        writeln!(temp, "test")?;
        temp.flush()?;

        let path = temp.path();
        let strategy = determine_strategy(Some(path), path, CompressionFormat::None);

        match strategy {
            WriteStrategy::Append { path: p } => {
                assert_eq!(p, path);
            }
            _ => panic!("Expected Append strategy, got {:?}", strategy),
        }

        Ok(())
    }

    #[test]
    fn test_atomic_swap_compressed_same_file() -> Result<(), Box<dyn std::error::Error>> {
        let mut temp = NamedTempFile::with_suffix(".json.archive.gz")?;
        writeln!(temp, "test")?;
        temp.flush()?;

        let path = temp.path();
        let strategy = determine_strategy(Some(path), path, CompressionFormat::Gzip);

        match strategy {
            WriteStrategy::AtomicSwap {
                path: p,
                compression,
                temp_path,
            } => {
                assert_eq!(p, path);
                assert_eq!(compression, CompressionFormat::Gzip);
                assert!(temp_path.to_string_lossy().contains(".json.archive.gz"));
            }
            _ => panic!("Expected AtomicSwap strategy, got {:?}", strategy),
        }

        Ok(())
    }

    #[test]
    fn test_direct_different_files() -> Result<(), Box<dyn std::error::Error>> {
        let mut source = NamedTempFile::with_suffix(".json.archive")?;
        writeln!(source, "test")?;
        source.flush()?;

        let dest = Path::new("/tmp/different.json.archive");
        let strategy = determine_strategy(Some(source.path()), dest, CompressionFormat::None);

        match strategy {
            WriteStrategy::CopyOnWrite { input, output } => {
                assert_eq!(input.0, source.path());
                assert_eq!(input.1, CompressionFormat::None);
                assert_eq!(output.0, PathBuf::from("/tmp/different.json.archive"));
                assert_eq!(output.1, CompressionFormat::None);
            }
            _ => panic!("Expected Direct strategy, got {:?}", strategy),
        }

        Ok(())
    }

    #[test]
    fn test_direct_transcode_compression() -> Result<(), Box<dyn std::error::Error>> {
        let mut source = NamedTempFile::with_suffix(".json.archive.gz")?;
        writeln!(source, "test")?;
        source.flush()?;

        let dest = Path::new("/tmp/output.json.archive.br");
        let strategy = determine_strategy(Some(source.path()), dest, CompressionFormat::Gzip);

        match strategy {
            WriteStrategy::CopyOnWrite { input, output } => {
                assert_eq!(input.1, CompressionFormat::Gzip);
                assert_eq!(output.1, CompressionFormat::Brotli);
            }
            _ => panic!("Expected Direct strategy, got {:?}", strategy),
        }

        Ok(())
    }
}