sqlitegraph 2.0.7

//! Database restore API for SQLiteGraph
//!
//! Provides user-friendly restore functionality that loads database
//! snapshots from backup and verifies integrity before restoration.

use crate::backend::native::{
    types::{NativeBackendError, NativeResult},
    v2::{
        export::ExportMode,
        export::manifest::ManifestSerializer,
        import::ImportMode,
        import::snapshot::{SnapshotImportConfig, SnapshotImporter},
    },
};
use std::path::{Path, PathBuf};

/// Configuration for restore operations
#[derive(Debug, Clone)]
pub struct RestoreConfig {
    /// Path to the backup directory (contains snapshot + manifest)
    pub backup_dir: PathBuf,

    /// Target path for restored database
    pub target_path: PathBuf,

    /// Whether to overwrite existing target file (default: false)
    pub overwrite_existing: bool,

    /// Whether to validate manifest strictly (default: true)
    pub validate_manifest: bool,

    /// Whether to verify checksum (default: true)
    pub verify_checksum: bool,

    /// Import mode - Fresh is required for snapshots
    pub import_mode: ImportMode,
}

impl Default for RestoreConfig {
    fn default() -> Self {
        Self {
            backup_dir: PathBuf::from("backup"),
            target_path: PathBuf::from("restored.v2"),
            overwrite_existing: false,
            validate_manifest: true,
            verify_checksum: true,
            import_mode: ImportMode::Fresh,
        }
    }
}

impl RestoreConfig {
    /// Create a new restore config with backup directory and target path
    pub fn new(backup_dir: impl AsRef<Path>, target_path: impl AsRef<Path>) -> Self {
        Self {
            backup_dir: backup_dir.as_ref().to_path_buf(),
            target_path: target_path.as_ref().to_path_buf(),
            ..Default::default()
        }
    }

    /// Set whether to overwrite existing target file
    pub fn with_overwrite(mut self, allow: bool) -> Self {
        self.overwrite_existing = allow;
        self
    }

    /// Set whether to validate manifest strictly
    pub fn with_validation(mut self, enabled: bool) -> Self {
        self.validate_manifest = enabled;
        self
    }

    /// Set whether to verify checksum
    pub fn with_checksum_verification(mut self, enabled: bool) -> Self {
        self.verify_checksum = enabled;
        self
    }
}

/// Result of a restore operation
#[derive(Debug, Clone)]
pub struct RestoreResult {
    /// Path to restored database file
    pub restored_path: PathBuf,

    /// Number of records imported
    pub records_imported: u64,

    /// Import duration in seconds
    pub duration_secs: f64,

    /// Checksum of restored database
    pub checksum: u64,

    /// Whether validation passed
    pub validation_passed: bool,

    /// Final recovery state
    pub recovery_state: String,
}

/// Restore a database from a backup snapshot
///
/// This function loads a database snapshot from the backup directory,
/// validates the manifest, verifies the checksum, and creates a restored
/// database at the target path.
///
/// # Arguments
///
/// * `config` - Restore configuration specifying backup location and options
///
/// # Returns
///
/// Returns `RestoreResult` containing information about the restored database
///
/// # Errors
///
/// Returns an error if:
/// - Backup directory does not exist
/// - Manifest file is missing or invalid
/// - Backup is not a snapshot export
/// - Target file exists and overwrite is disabled
/// - Snapshot file is missing or corrupted
/// - Checksum verification fails
///
/// # Example
///
/// ```no_run
/// use sqlitegraph::backend::native::v2::restore::{restore_backup, RestoreConfig};
/// use std::path::Path;
///
/// let config = RestoreConfig::new(
///     Path::new("backups/my_backup"),
///     Path::new("restored.v2")
/// )
/// .with_overwrite(true);
///
/// let result = restore_backup(config)?;
/// # Ok::<(), sqlitegraph::backend::native::NativeBackendError>(())
/// ```
pub fn restore_backup(config: RestoreConfig) -> NativeResult<RestoreResult> {
    // Step 1: Validate backup directory exists
    if !config.backup_dir.exists() {
        return Err(NativeBackendError::InvalidParameter {
            context: format!("Backup directory does not exist: {:?}", config.backup_dir),
            source: None,
        });
    }

    // Step 2: Read and validate manifest
    let manifest_path = config.backup_dir.join("export.manifest");
    if !manifest_path.exists() {
        return Err(NativeBackendError::InvalidParameter {
            context: format!("Manifest not found: {:?}", manifest_path),
            source: None,
        });
    }

    let manifest = if config.validate_manifest {
        ManifestSerializer::read_from_file(&manifest_path)?
    } else {
        ManifestSerializer::read_from_file(&manifest_path)?
    };

    // Step 3: Verify this is a snapshot export
    if manifest.export_mode != ExportMode::Snapshot {
        return Err(NativeBackendError::InvalidParameter {
            context: format!("Backup is not a snapshot: {:?}", manifest.export_mode),
            source: None,
        });
    }

    // Step 4: Check target path
    if config.target_path.exists() && !config.overwrite_existing {
        return Err(NativeBackendError::InvalidParameter {
            context: format!(
                "Target file exists and overwrite disabled: {:?}",
                config.target_path
            ),
            source: None,
        });
    }

    // Step 5: Create import config
    let import_config = SnapshotImportConfig {
        target_graph_path: config.target_path.clone(),
        export_dir_path: config.backup_dir.clone(),
        import_mode: config.import_mode,
        validate_manifest: config.validate_manifest,
        verify_checksum: config.verify_checksum,
        overwrite_existing: config.overwrite_existing,
    };

    // Step 6: Create importer and import
    let importer = SnapshotImporter::from_export_dir(
        &config.backup_dir,
        &config.target_path,
        import_config.clone(),
    )?;

    let import_result = importer.import()?;

    // Step 7: Convert to RestoreResult
    Ok(RestoreResult {
        restored_path: config.target_path.clone(),
        records_imported: import_result.records_imported,
        duration_secs: import_result.import_duration.as_secs_f64(),
        checksum: import_result.imported_checksum,
        validation_passed: import_result.validation_passed,
        recovery_state: format!("{:?}", import_result.final_recovery_state),
    })
}

/// Quick restore with default configuration
///
/// Convenience function that restores a backup using default settings:
/// - Manifest validation: enabled
/// - Checksum verification: enabled
/// - Overwrite existing: disabled
/// - Import mode: Fresh
///
/// # Arguments
///
/// * `backup_dir` - Directory containing the backup files
/// * `target_path` - Path where the restored database will be created
///
/// # Returns
///
/// Returns `RestoreResult` containing information about the restored database
///
/// # Errors
///
/// Returns an error if:
/// - Backup directory does not exist
/// - Manifest file is missing or invalid
/// - Target file already exists
/// - Snapshot file is missing or corrupted
///
/// # Example
///
/// ```no_run
/// use sqlitegraph::backend::native::v2::restore::restore;
/// use std::path::Path;
///
/// let result = restore(
///     Path::new("backups/my_backup"),
///     Path::new("restored.v2")
/// )?;
/// # Ok::<(), sqlitegraph::backend::native::NativeBackendError>(())
/// ```
pub fn restore(backup_dir: &Path, target_path: &Path) -> NativeResult<RestoreResult> {
    restore_backup(RestoreConfig::new(backup_dir, target_path))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::backend::native::v2::export::snapshot::{SnapshotExportConfig, SnapshotExporter};
    use crate::backend::native::v2::export::manifest::ExportManifest;
    use tempfile::TempDir;

    /// Create a test snapshot for restore testing
    fn create_test_snapshot(export_dir: &Path) -> NativeResult<(PathBuf, ExportManifest)> {
        // Create a temporary source graph
        let graph_path = export_dir.join("source.v2");
        let _graph = crate::backend::native::graph_file::GraphFile::create(&graph_path)?;

        // Create snapshot export
        let config = SnapshotExportConfig {
            export_path: export_dir.to_path_buf(),
            snapshot_id: "test_snapshot".to_string(),
            include_statistics: true,
            min_stable_duration: std::time::Duration::from_secs(0),
            checksum_validation: true,
        };

        let mut exporter = SnapshotExporter::new(&graph_path, config)?;
        let _export_result = exporter.export_snapshot()?;

        // Read manifest
        let manifest_path = export_dir.join("export.manifest");
        let manifest = ManifestSerializer::read_from_file(&manifest_path)?;

        Ok((graph_path, manifest))
    }

    #[test]
    fn test_restore_config_default() {
        let config = RestoreConfig::default();

        assert_eq!(config.backup_dir, PathBuf::from("backup"));
        assert_eq!(config.target_path, PathBuf::from("restored.v2"));
        assert_eq!(config.overwrite_existing, false);
        assert_eq!(config.validate_manifest, true);
        assert_eq!(config.verify_checksum, true);
    }

    #[test]
    fn test_restore_config_builder() {
        let config = RestoreConfig::new("test_backup", "test_restored.v2")
            .with_overwrite(true)
            .with_validation(false)
            .with_checksum_verification(false);

        assert_eq!(config.backup_dir, PathBuf::from("test_backup"));
        assert_eq!(config.target_path, PathBuf::from("test_restored.v2"));
        assert_eq!(config.overwrite_existing, true);
        assert_eq!(config.validate_manifest, false);
        assert_eq!(config.verify_checksum, false);
    }

    #[test]
    fn test_restore_rejects_missing_backup_dir() {
        let temp_dir = TempDir::new().unwrap();
        let missing_dir = temp_dir.path().join("nonexistent_backup");
        let target_path = temp_dir.path().join("restored.v2");

        let result = restore(&missing_dir, &target_path);

        assert!(result.is_err());
        match result {
            Err(NativeBackendError::InvalidParameter { context, .. }) => {
                assert!(context.contains("does not exist"));
            }
            _ => panic!("Expected InvalidParameter error"),
        }
    }

    #[test]
    fn test_restore_rejects_missing_manifest() {
        let temp_dir = TempDir::new().unwrap();
        let backup_dir = temp_dir.path().join("incomplete_backup");
        std::fs::create_dir(&backup_dir).unwrap();

        let target_path = temp_dir.path().join("restored.v2");

        let result = restore(&backup_dir, &target_path);

        assert!(result.is_err());
        match result {
            Err(NativeBackendError::InvalidParameter { context, .. }) => {
                assert!(context.contains("Manifest not found"));
            }
            _ => panic!("Expected InvalidParameter error"),
        }
    }

    #[test]
    fn test_restore_rejects_overwrite_without_flag() {
        let temp_dir = TempDir::new().unwrap();

        // Create an existing target file
        let target_path = temp_dir.path().join("existing.v2");
        std::fs::write(&target_path, b"existing data").unwrap();

        // Create a backup directory (without manifest, will fail before overwrite check)
        let backup_dir = temp_dir.path().join("backup");
        std::fs::create_dir(&backup_dir).unwrap();

        // Using RestoreConfig directly to test overwrite flag logic
        let config = RestoreConfig::new(&backup_dir, &target_path).with_overwrite(false);

        let result = restore_backup(config);

        // Should fail with manifest not found (before overwrite check)
        assert!(result.is_err());
    }

    #[test]
    fn test_restore_accepts_overwrite_with_flag() {
        let temp_dir = TempDir::new().unwrap();

        // Create a valid snapshot backup
        let backup_dir = temp_dir.path().join("backup");
        std::fs::create_dir(&backup_dir).unwrap();
        let (_source_path, _manifest) = create_test_snapshot(&backup_dir).unwrap();

        // Create an existing target file
        let target_path = temp_dir.path().join("existing.v2");
        std::fs::write(&target_path, b"existing data").unwrap();

        // Use overwrite flag
        let config = RestoreConfig::new(&backup_dir, &target_path).with_overwrite(true);

        let result = restore_backup(config);

        // Should succeed (or fail on other issues, but not overwrite protection)
        // The actual restore may fail if target file isn't a valid GraphFile,
        // but overwrite check should pass
        match result {
            Ok(_) => {
                // Restore succeeded
                assert!(target_path.exists());
            }
            Err(e) => {
                // May fail due to non-GraphFile target, but not due to overwrite protection
                let err_msg = format!("{:?}", e);
                assert!(
                    !err_msg.contains("overwrite disabled"),
                    "Should not fail due to overwrite protection when flag is set"
                );
            }
        }
    }

    #[test]
    fn test_backup_restore_roundtrip() {
        let temp_dir = TempDir::new().unwrap();

        // Create a snapshot backup
        let backup_dir = temp_dir.path().join("backup");
        std::fs::create_dir(&backup_dir).unwrap();
        let (_source_path, manifest) = create_test_snapshot(&backup_dir).unwrap();

        // Verify manifest was created
        assert!(backup_dir.join("export.manifest").exists());

        // Restore from backup
        let restore_path = temp_dir.path().join("restored.v2");
        let result = restore(&backup_dir, &restore_path);

        assert!(result.is_ok(), "Restore should succeed: {:?}", result.err());

        let restore_result = result.unwrap();
        assert!(restore_path.exists());
        assert_eq!(restore_result.restored_path, restore_path);
        assert!(restore_result.validation_passed);

        // Verify the restored file can be opened
        let restored_graph = crate::backend::native::graph_file::GraphFile::open(&restore_path);
        assert!(
            restored_graph.is_ok(),
            "Restored file should be a valid GraphFile"
        );

        // Verify record counts match
        let restored = restored_graph.unwrap();
        assert_eq!(
            restored.persistent_header().node_count as u64,
            manifest.total_records
        );
    }

    #[test]
    fn test_restore_creates_result_with_correct_fields() {
        let temp_dir = TempDir::new().unwrap();

        // Create a snapshot backup
        let backup_dir = temp_dir.path().join("backup");
        std::fs::create_dir(&backup_dir).unwrap();
        create_test_snapshot(&backup_dir).unwrap();

        // Restore from backup
        let restore_path = temp_dir.path().join("restored.v2");
        let result = restore(&backup_dir, &restore_path).unwrap();

        // Verify all fields are populated
        assert_eq!(result.restored_path, restore_path);
        assert!(result.records_imported >= 0);
        assert!(result.duration_secs >= 0.0);
        assert!(result.validation_passed);
        assert!(!result.recovery_state.is_empty());
    }
}