json_archive/

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

//! Unified writer abstraction for compressed and uncompressed output.
//!
//! This module provides `CompressionWriter`, an enum that wraps different
//! compression encoders behind a common interface implementing `std::io::Write`.
//!
//! The goal is to simplify write logic by allowing callers to write to any
//! compression format using the same API, with proper error handling that
//! produces user-friendly diagnostics.

use std::fs::File;
use std::io::{BufWriter, Write};
use std::path::Path;

use crate::detection::CompressionFormat;
use crate::diagnostics::{Diagnostic, DiagnosticCode};

/// A writer that handles optional compression transparently.
///
/// Wraps different compression encoders behind a unified interface
/// that implements `Write` and provides a `finish()` method for cleanup.
///
/// # Example
///
/// ```ignore
/// use json_archive::compression_writer::CompressionWriter;
/// use json_archive::detection::CompressionFormat;
/// use std::io::Write;
///
/// let mut writer = CompressionWriter::create(path, CompressionFormat::Gzip)?;
/// writeln!(writer, "some data")?;
/// writer.finish()?;
/// ```
// Note: Cannot derive Debug because compression encoder types don't implement Debug
pub enum CompressionWriter {
    /// Uncompressed output - uses BufWriter since File has no internal buffering
    Plain(BufWriter<File>),
    /// Compression encoders write directly to File - they do their own internal buffering
    #[cfg(feature = "compression")]
    Gzip(flate2::write::GzEncoder<File>),
    #[cfg(feature = "compression")]
    Zlib(flate2::write::ZlibEncoder<File>),
    #[cfg(feature = "compression")]
    Zstd(zstd::stream::write::Encoder<'static, File>),
    #[cfg(feature = "compression")]
    Brotli(brotli::CompressorWriter<File>),
}

impl CompressionWriter {
    /// Open a file for writing with the specified compression format.
    ///
    /// # Errors
    ///
    /// Returns a diagnostic explaining:
    /// - What file we tried to create
    /// - What compression format was requested
    /// - Why it failed (permissions, disk full, unsupported format, etc.)
    pub fn create(path: &Path, format: CompressionFormat) -> Result<Self, Vec<Diagnostic>> {
        let file = File::create(path).map_err(|e| {
            vec![Diagnostic::fatal(
                DiagnosticCode::PathNotFound,
                format!(
                    "I couldn't create the output file '{}': {}",
                    path.display(),
                    describe_io_error(&e)
                ),
            )
            .with_advice(advice_for_create_error(&e, path))]
        })?;

        match format {
            // Plain needs BufWriter since File has no internal buffering
            CompressionFormat::None => Ok(Self::Plain(BufWriter::new(file))),

            // Compression encoders do their own buffering, write directly to File
            #[cfg(feature = "compression")]
            CompressionFormat::Gzip => {
                use flate2::write::GzEncoder;
                use flate2::Compression;
                Ok(Self::Gzip(GzEncoder::new(file, Compression::default())))
            }

            #[cfg(feature = "compression")]
            CompressionFormat::Zlib => {
                use flate2::write::ZlibEncoder;
                use flate2::Compression;
                Ok(Self::Zlib(ZlibEncoder::new(file, Compression::default())))
            }

            #[cfg(feature = "compression")]
            CompressionFormat::Deflate => {
                // Deflate is a raw compression algorithm, not a container format.
                // We can read deflate data, but when writing we need to pick a
                // container (gzip or zlib) that provides headers and checksums.
                Err(vec![Diagnostic::fatal(
                    DiagnosticCode::UnsupportedVersion,
                    "I can't write raw deflate format because it's not a container format.".to_string(),
                )
                .with_advice(
                    "Deflate is a compression algorithm, not a file format. When writing, \
                     you need to choose a container format that wraps deflate data:\n\
                     \n  - Use .gz (gzip) for general-purpose compression\n  \
                     - Use .zlib for zlib-wrapped deflate\n\
                     \nIf you're appending to an existing deflate file, consider converting \
                     it to gzip first.".to_string()
                )])
            }

            #[cfg(feature = "compression")]
            CompressionFormat::Zstd => {
                let encoder = zstd::stream::write::Encoder::new(file, 0).map_err(|e| {
                    vec![Diagnostic::fatal(
                        DiagnosticCode::PathNotFound,
                        format!(
                            "I couldn't initialize zstd compression for '{}': {}",
                            path.display(),
                            e
                        ),
                    )]
                })?;
                Ok(Self::Zstd(encoder))
            }

            #[cfg(feature = "compression")]
            CompressionFormat::Brotli => {
                // buffer_size=4096, quality=11 (max), lgwin=22 (default window)
                Ok(Self::Brotli(brotli::CompressorWriter::new(
                    file, 4096, 11, 22,
                )))
            }

            #[cfg(not(feature = "compression"))]
            _ => Err(vec![Diagnostic::fatal(
                DiagnosticCode::UnsupportedVersion,
                format!(
                    "I can't write {} compressed files because this build doesn't include compression support.",
                    format_name(format)
                ),
            )
            .with_advice("Rebuild with: cargo build --features compression".to_string())]),
        }
    }

    /// Finish writing and flush all buffers.
    ///
    /// For compressed formats, this finalizes the compression stream.
    /// Must be called before dropping to ensure all data is written.
    ///
    /// # Errors
    ///
    /// Returns a diagnostic if flushing or finalizing fails.
    ///
    /// **Important**: This method does not clean up the output file on error.
    /// If `finish()` fails, the caller is responsible for removing the
    /// partially-written file themselves:
    ///
    /// ```ignore
    /// if let Err(diagnostics) = writer.finish() {
    ///     let _ = std::fs::remove_file(&path);
    ///     return Err(diagnostics);
    /// }
    /// ```
    pub fn finish(self) -> Result<(), Vec<Diagnostic>> {
        match self {
            Self::Plain(mut w) => w.flush().map_err(|e| {
                vec![Diagnostic::fatal(
                    DiagnosticCode::PathNotFound,
                    format!(
                        "I couldn't flush the output file: {}",
                        describe_io_error(&e)
                    ),
                )]
            }),

            #[cfg(feature = "compression")]
            Self::Gzip(encoder) => {
                encoder.finish().map_err(|e| {
                    vec![Diagnostic::fatal(
                        DiagnosticCode::PathNotFound,
                        format!(
                            "I couldn't finalize gzip compression: {}",
                            describe_io_error(&e)
                        ),
                    )]
                })?;
                Ok(())
            }

            #[cfg(feature = "compression")]
            Self::Zlib(encoder) => {
                encoder.finish().map_err(|e| {
                    vec![Diagnostic::fatal(
                        DiagnosticCode::PathNotFound,
                        format!(
                            "I couldn't finalize zlib compression: {}",
                            describe_io_error(&e)
                        ),
                    )]
                })?;
                Ok(())
            }

            #[cfg(feature = "compression")]
            Self::Zstd(encoder) => {
                encoder.finish().map_err(|e| {
                    vec![Diagnostic::fatal(
                        DiagnosticCode::PathNotFound,
                        format!(
                            "I couldn't finalize zstd compression: {}",
                            describe_io_error(&e)
                        ),
                    )]
                })?;
                Ok(())
            }

            #[cfg(feature = "compression")]
            Self::Brotli(mut encoder) => {
                // Brotli uses a different API - no finish() method
                // Flush the encoder (brotli auto-flushes on drop, but we flush explicitly)
                encoder.flush().map_err(|e| {
                    vec![Diagnostic::fatal(
                        DiagnosticCode::PathNotFound,
                        format!(
                            "I couldn't finalize brotli compression: {}",
                            describe_io_error(&e)
                        ),
                    )]
                })
            }
        }
    }
}

impl Write for CompressionWriter {
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
        match self {
            Self::Plain(w) => w.write(buf),
            #[cfg(feature = "compression")]
            Self::Gzip(w) => w.write(buf),
            #[cfg(feature = "compression")]
            Self::Zlib(w) => w.write(buf),
            #[cfg(feature = "compression")]
            Self::Zstd(w) => w.write(buf),
            #[cfg(feature = "compression")]
            Self::Brotli(w) => w.write(buf),
        }
    }

    fn flush(&mut self) -> std::io::Result<()> {
        match self {
            Self::Plain(w) => w.flush(),
            #[cfg(feature = "compression")]
            Self::Gzip(w) => w.flush(),
            #[cfg(feature = "compression")]
            Self::Zlib(w) => w.flush(),
            #[cfg(feature = "compression")]
            Self::Zstd(w) => w.flush(),
            #[cfg(feature = "compression")]
            Self::Brotli(w) => w.flush(),
        }
    }
}

/// Translate io::Error into human-readable descriptions.
fn describe_io_error(e: &std::io::Error) -> String {
    match e.kind() {
        std::io::ErrorKind::NotFound => "the directory doesn't exist".to_string(),
        std::io::ErrorKind::PermissionDenied => "permission denied".to_string(),
        std::io::ErrorKind::AlreadyExists => {
            "a directory with that name already exists".to_string()
        }
        std::io::ErrorKind::StorageFull => "the disk is full".to_string(),
        std::io::ErrorKind::ReadOnlyFilesystem => "the filesystem is read-only".to_string(),
        _ => e.to_string(),
    }
}

/// Generate helpful advice based on the error type.
fn advice_for_create_error(e: &std::io::Error, path: &Path) -> String {
    match e.kind() {
        std::io::ErrorKind::NotFound => {
            if let Some(parent) = path.parent() {
                format!(
                    "The parent directory '{}' doesn't exist. Create it first with:\n  mkdir -p '{}'",
                    parent.display(),
                    parent.display()
                )
            } else {
                "Check that the path is valid.".to_string()
            }
        }
        std::io::ErrorKind::PermissionDenied => {
            format!(
                "You don't have write permission for this location. Try:\n  ls -la '{}'",
                path.parent()
                    .map(|p| p.display().to_string())
                    .unwrap_or_else(|| ".".to_string())
            )
        }
        std::io::ErrorKind::StorageFull => {
            "Free up disk space or write to a different location.".to_string()
        }
        _ => "Check that the path is valid and you have write permission.".to_string(),
    }
}

/// Get a human-readable name for a compression format.
#[cfg(not(feature = "compression"))]
fn format_name(format: CompressionFormat) -> &'static str {
    match format {
        CompressionFormat::Gzip => "gzip",
        CompressionFormat::Zlib => "zlib",
        CompressionFormat::Zstd => "zstd",
        CompressionFormat::Brotli => "brotli",
        CompressionFormat::Deflate => "deflate",
        CompressionFormat::None => "uncompressed",
    }
}

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

    #[test]
    fn test_plain_writer() -> Result<(), Box<dyn std::error::Error>> {
        let temp_file = NamedTempFile::new()?;
        let path = temp_file.path();

        {
            let mut writer = CompressionWriter::create(path, CompressionFormat::None)
                .map_err(|d| format!("{:?}", d))?;
            writeln!(writer, "hello world").map_err(|e| format!("{}", e))?;
            writer.finish().map_err(|d| format!("{:?}", d))?;
        }

        let content = std::fs::read_to_string(path)?;
        assert_eq!(content, "hello world\n");
        Ok(())
    }

    #[test]
    #[cfg(feature = "compression")]
    fn test_gzip_writer() -> Result<(), Box<dyn std::error::Error>> {
        use flate2::read::GzDecoder;

        let temp_file = NamedTempFile::new()?;
        let path = temp_file.path();

        {
            let mut writer = CompressionWriter::create(path, CompressionFormat::Gzip)
                .map_err(|d| format!("{:?}", d))?;
            writeln!(writer, "hello gzip").map_err(|e| format!("{}", e))?;
            writer.finish().map_err(|d| format!("{:?}", d))?;
        }

        // Verify by decompressing
        let file = File::open(path)?;
        let mut decoder = GzDecoder::new(file);
        let mut content = String::new();
        decoder.read_to_string(&mut content)?;
        assert_eq!(content, "hello gzip\n");
        Ok(())
    }

    #[test]
    #[cfg(feature = "compression")]
    fn test_zstd_writer() -> Result<(), Box<dyn std::error::Error>> {
        let temp_file = NamedTempFile::new()?;
        let path = temp_file.path();

        {
            let mut writer = CompressionWriter::create(path, CompressionFormat::Zstd)
                .map_err(|d| format!("{:?}", d))?;
            writeln!(writer, "hello zstd").map_err(|e| format!("{}", e))?;
            writer.finish().map_err(|d| format!("{:?}", d))?;
        }

        // Verify by decompressing
        let file = File::open(path)?;
        let mut decoder = zstd::stream::read::Decoder::new(file)?;
        let mut content = String::new();
        decoder.read_to_string(&mut content)?;
        assert_eq!(content, "hello zstd\n");
        Ok(())
    }

    #[test]
    fn test_create_nonexistent_directory() {
        let result = CompressionWriter::create(
            Path::new("/nonexistent/directory/file.txt"),
            CompressionFormat::None,
        );
        match result {
            Ok(_) => panic!("Expected error for nonexistent directory"),
            Err(diagnostics) => {
                assert_eq!(diagnostics.len(), 1);
                // The error message should mention the path
                assert!(
                    diagnostics[0]
                        .description
                        .contains("/nonexistent/directory/file.txt"),
                    "Expected path in error message, got: {}",
                    diagnostics[0].description
                );
            }
        }
    }
}