json_archive/

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

//! File type detection for JSON archives.
//!
//! This module exists to support ergonomic command-line usage without requiring
//! `--archive=filename` flags. The goal is to infer intent just from filenames:
//!
//! - `json-archive data.json.archive data.json` -> append data.json to existing archive
//! - `json-archive data.json` -> create new archive from data.json
//! - `json-archive data.json.archive.tmp foo.json bar.json` -> append to archive with .tmp suffix
//!
//! Design choice by @nobody. No user requests for this, just seemed nice.

use std::fs::File;
use std::io::{BufRead, BufReader, Read};
use std::path::Path;

#[cfg(feature = "compression")]
use brotli::Decompressor;
#[cfg(feature = "compression")]
use flate2::read::{DeflateDecoder, GzDecoder, ZlibDecoder};
#[cfg(feature = "compression")]
use zstd::stream::read::Decoder as ZstdDecoder;

/// Detects if a file is a JSON archive by checking file extension or inspecting the header.
///
/// Detection strategy:
/// 1. Check if filename ends with .json.archive
/// 2. Inspect first line for type field as first key with value "@peoplesgrocers/json-archive"
///
/// Strategy 2 was added by @nobody based on frustration with the Elm compiler,
/// which requires specific file extensions (like .js) while build systems often generate
/// temporary files with arbitrary suffixes like .tmp. @nobody thought it would be nice if the CLI
/// was robust enough to handle this.
///
///
/// The magic value "@peoplesgrocers/json-archive" in the type field works as a file
/// signature for cases where the extension isn't what we expect. Not requested by anyone,
/// just anticipating potential tooling conflicts.
pub fn is_json_archive<P: AsRef<Path>>(path: P) -> Result<bool, std::io::Error> {
    let path = path.as_ref();

    // Check file extension first (fast path)
    if let Some(filename) = path.file_name() {
        if let Some(filename_str) = filename.to_str() {
            // Match .json.archive with any compression suffix
            if filename_str.ends_with(".json.archive")
                || filename_str.ends_with(".json.archive.gz")
                || filename_str.ends_with(".json.archive.br")
                || filename_str.ends_with(".json.archive.zst")
                || filename_str.ends_with(".json.archive.zlib")
            {
                return Ok(true);
            }
        }
    }

    // Open file and detect compression
    let mut file = File::open(path)?;
    let mut magic_bytes = [0u8; 4];
    let bytes_read = file.read(&mut magic_bytes)?;
    let compression = detect_compression_format(path, &magic_bytes[..bytes_read]);

    // Reopen file to reset position
    file = File::open(path)?;

    // Create appropriate reader based on compression format
    let reader: Box<dyn BufRead> = create_reader(file, compression)?;

    check_header_line(reader)
}

/// Create a buffered reader that handles decompression if needed.
#[cfg(feature = "compression")]
fn create_reader(file: File, compression: CompressionFormat) -> Result<Box<dyn BufRead>, std::io::Error> {
    Ok(match compression {
        CompressionFormat::Gzip => Box::new(BufReader::new(GzDecoder::new(file))),
        CompressionFormat::Deflate => Box::new(BufReader::new(DeflateDecoder::new(file))),
        CompressionFormat::Zlib => Box::new(BufReader::new(ZlibDecoder::new(file))),
        CompressionFormat::Brotli => Box::new(BufReader::new(Decompressor::new(file, 4096))),
        CompressionFormat::Zstd => Box::new(BufReader::new(ZstdDecoder::new(file)?)),
        CompressionFormat::None => Box::new(BufReader::new(file)),
    })
}

#[cfg(not(feature = "compression"))]
fn create_reader(file: File, compression: CompressionFormat) -> Result<Box<dyn BufRead>, std::io::Error> {
    if compression != CompressionFormat::None {
        // Without compression support, we can't decompress to check the header.
        // Return false by returning an empty reader that will fail header check.
        return Ok(Box::new(BufReader::new(std::io::empty())));
    }
    Ok(Box::new(BufReader::new(file)))
}

/// Check if the first line of the reader contains a valid archive header.
fn check_header_line(mut reader: Box<dyn BufRead>) -> Result<bool, std::io::Error> {
    let mut first_line = String::new();

    match reader.read_line(&mut first_line) {
        Ok(0) => Ok(false), // Empty file
        Ok(_) => {
            // Try to parse as JSON and check if it has our type field as the first key
            if let Ok(value) = serde_json::from_str::<serde_json::Value>(&first_line) {
                if let Some(obj) = value.as_object() {
                    // Check if the first key is "type" with our expected value
                    // Note: serde_json::Map preserves insertion order
                    if let Some((first_key, first_value)) = obj.iter().next() {
                        if first_key == "type" {
                            if let Some(type_str) = first_value.as_str() {
                                return Ok(type_str == "@peoplesgrocers/json-archive");
                            }
                        }
                    }
                }
            }
            Ok(false)
        }
        Err(e) => Err(e),
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CompressionFormat {
    Gzip,
    Deflate,
    Zlib,
    Brotli,
    Zstd,
    None,
}

pub fn detect_compression_format(path: &Path, bytes: &[u8]) -> CompressionFormat {
    if bytes.len() < 4 {
        return CompressionFormat::None;
    }

    // Gzip magic number: 0x1f 0x8b
    if bytes[0] == 0x1f && bytes[1] == 0x8b {
        return CompressionFormat::Gzip;
    }

    // Zlib magic number: 0x78 followed by 0x01, 0x5e, 0x9c, or 0xda
    if bytes[0] == 0x78 && (bytes[1] == 0x01 || bytes[1] == 0x5e || bytes[1] == 0x9c || bytes[1] == 0xda) {
        return CompressionFormat::Zlib;
    }

    // Zstd magic number: 0x28 0xb5 0x2f 0xfd
    if bytes.len() >= 4 && bytes[0] == 0x28 && bytes[1] == 0xb5 && bytes[2] == 0x2f && bytes[3] == 0xfd {
        return CompressionFormat::Zstd;
    }

    // Check file extension for brotli (no reliable magic number) and deflate
    if let Some(ext) = path.extension() {
        let ext_str = ext.to_string_lossy();
        if ext_str == "br" || path.to_string_lossy().contains(".br.") {
            return CompressionFormat::Brotli;
        }
        if ext_str == "deflate" {
            return CompressionFormat::Deflate;
        }
    }

    CompressionFormat::None
}

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

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

        assert!(is_json_archive(temp_file.path())?);
        Ok(())
    }

    #[test]
    fn test_detect_by_type_field() -> Result<(), Box<dyn std::error::Error>> {
        let mut temp_file = NamedTempFile::with_suffix(".weird-extension")?;
        writeln!(
            temp_file,
            r#"{{"type":"@peoplesgrocers/json-archive","version":1}}"#
        )?;
        temp_file.flush()?;

        assert!(is_json_archive(temp_file.path())?);
        Ok(())
    }

    #[test]
    fn test_detect_by_type_field_with_tmp_extension() -> Result<(), Box<dyn std::error::Error>> {
        let mut temp_file = NamedTempFile::with_suffix(".json.tmp")?;
        writeln!(
            temp_file,
            r#"{{"type":"@peoplesgrocers/json-archive","version":1}}"#
        )?;
        temp_file.flush()?;

        assert!(is_json_archive(temp_file.path())?);
        Ok(())
    }

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

        assert!(!is_json_archive(temp_file.path())?);
        Ok(())
    }

    #[test]
    fn test_not_archive_wrong_type_field() -> Result<(), Box<dyn std::error::Error>> {
        let mut temp_file = NamedTempFile::with_suffix(".tmp")?;
        writeln!(temp_file, r#"{{"type":"something-else","version":1}}"#)?;
        temp_file.flush()?;

        assert!(!is_json_archive(temp_file.path())?);
        Ok(())
    }

    #[test]
    fn test_not_archive_type_not_first_field() -> Result<(), Box<dyn std::error::Error>> {
        let mut temp_file = NamedTempFile::with_suffix(".tmp")?;
        // Use a key that comes after "type" alphabetically to ensure it's first
        writeln!(
            temp_file,
            r#"{{"version":1,"zzz":"@peoplesgrocers/json-archive"}}"#
        )?;
        temp_file.flush()?;

        // This should NOT be detected as an archive since the type field doesn't exist
        assert!(!is_json_archive(temp_file.path())?);
        Ok(())
    }

    #[test]
    fn test_not_archive_empty_file() -> Result<(), Box<dyn std::error::Error>> {
        let temp_file = NamedTempFile::with_suffix(".json")?;

        assert!(!is_json_archive(temp_file.path())?);
        Ok(())
    }

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

        assert!(!is_json_archive(temp_file.path())?);
        Ok(())
    }
}