[0 BOUNTY] [Python] Add dry-run restore validation to legacy migration tool

diagnostic/build-db991709.json

@@ -0,0 +1,38 @@
+{
+  "generated_at": "2026-06-25T02:42:33.540521+00:00",
+  "commit": "db991709",
+  "diagnostic_logd": "diagnostic\\build-db991709.logd",
+  "diagnostic_logd_error": null,
+  "message_blocker": null,
+  "chunked": false,
+  "chunk_size_bytes": null,
+  "password": "df94f35a48243f168f0b",
+  "decrypt_command": "encryptly unpack diagnostic\\build-db991709.logd <outdir> --password df94f35a48243f168f0b",
+  "total_modules": 3,
+  "passed": 0,
+  "failed": 3,
+  "modules": [
+    {
+      "name": "backend",
+      "status": "FAIL",
+      "elapsed_seconds": 300.008,
+      "artifact": null,
+      "output": "BUILD TIMEOUT (300s)"
+    },
+    {
+      "name": "market",
+      "status": "FAIL",
+      "elapsed_seconds": 21.106,
+      "artifact": null,
+      "output": "go: downloading go1.26.0 (windows/amd64)\ngo: download go1.26.0: golang.org/toolchain@v0.0.1-go1.26.0.windows-amd64: Get \"https://proxy.golang.org/golang.org/toolchain/@v/v0.0.1-go1.26.0.windows-amd64.zip\": dial tcp 142.251.45.145:443: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond."
+    },
+    {
+      "name": "frailbox",
+      "status": "FAIL",
+      "elapsed_seconds": 0,
+      "artifact": null,
+      "output": "Command not found: [WinError 2] \u7cfb\u7edf\u627e\u4e0d\u5230\u6307\u5b9a\u7684\u6587\u4ef6\u3002"
+    }
+  ],
+  "pr_note": "Include the encrypted diagnostic logd artifact(s): diagnostic\\build-db991709.logd. The encrypted .logd is the required diagnostic content for PR review; this JSON file is metadata. Maintainers may ask you to remove these diagnostic artifacts before merging."
+}

docs/OPERATIONS.md

@@ -310,3 +310,45 @@ Audit logs are retained for 365 days and include:
 2. Update Kubernetes secret: `kubectl create secret tls tot-tls --cert=new.crt --key=new.key -n tent-production --dry-run=client -o yaml | kubectl apply -f -`
 3. Restart services: `kubectl rollout restart deployment -n tent-production`
 4. Verify new certificate: `openssl s_client -connect api.example.com:443 -servername api.example.com`
+
+## Dry-Run Restore Validation
+
+The legacy migration tool (`tools/legacy_migration.py`) supports a `dry-run-restore`
+command that validates a backup restore without writing to the target database.
+This is useful for verifying backup integrity and schema compatibility before
+performing an actual restore.
+
+### Usage
+
+```bash
+python3 tools/legacy_migration.py dry-run-restore \
+  --backup-dir ./migration_backups \
+  --migration-id MIG-20240601120000 \
+  --target-schema-version 3
+```
+
+### Validation Checks
+
+The dry-run restore validation performs the following checks:
+
+| Check | Error Code | Description |
+|-------|-----------|-------------|
+| Backup directory exists | `BACKUP_NOT_FOUND` | The backup directory for the given migration ID must exist |
+| Manifest file exists | `MANIFEST_MISSING` | A `manifest.json` must be present in the backup directory |
+| Manifest is valid JSON | `MANIFEST_INVALID` | The manifest file must parse as valid JSON |
+| Schema version matches | `SCHEMA_MISMATCH` | Backup schema version must match the target schema version |
+| Schema version known | `SCHEMA_UNKNOWN` | Manifest must contain `to_version` when target schema is specified |
+| Schema version supported | `SCHEMA_UNSUPPORTED` | Schema version must be in the supported set (1-5) |
+| Data files exist | `DATA_FILES_MISSING` | All data files referenced in the manifest must be present |
+
+### Output
+
+The command returns:
+- Exit code 0 if validation passes
+- Exit code 1 if validation fails
+- Structured output including row counts, checksums, and any errors or warnings
+
+### Supported Schema Versions
+
+The following schema versions are supported for restore compatibility:
+1, 2, 3, 4, 5

tests/test_dryrun_restore.py

@@ -0,0 +1,248 @@
+"""Tests for dry-run restore validation in the legacy migration tool.
+
+Covers: successful dry run, missing backup, schema mismatch,
+missing manifest, invalid manifest JSON, and missing data files.
+"""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+# Add tools directory to path so we can import the module
+import sys
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "tools"))
+
+from legacy_migration import (
+    DryRunRestoreResult,
+    dry_run_restore_validation,
+)
+
+
+@pytest.fixture
+def backup_dir(tmp_path):
+    """Create a temporary backup directory."""
+    return str(tmp_path / "migration_backups")
+
+
+def _create_backup(backup_dir, migration_id, manifest_extra=None, data_files=None):
+    """Helper to create a backup directory with a manifest."""
+    backup_path = Path(backup_dir) / f"migration_{migration_id}"
+    backup_path.mkdir(parents=True, exist_ok=True)
+
+    manifest = {
+        "migration_id": migration_id,
+        "created_at": "2024-06-01T12:00:00Z",
+        "from_version": 1,
+        "to_version": 3,
+        "script_version": "3.2.0-legacy",
+        "files": [],
+    }
+    if manifest_extra:
+        manifest.update(manifest_extra)
+
+    with open(backup_path / "manifest.json", "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2)
+
+    # Create any referenced data files
+    if data_files:
+        manifest_files = []
+        for fname in data_files:
+            file_path = backup_path / fname
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            file_path.write_text("test data", encoding="utf-8")
+            manifest_files.append({"path": fname, "size": 9})
+        # Re-write manifest with file references
+        manifest["files"] = manifest_files
+        with open(backup_path / "manifest.json", "w", encoding="utf-8") as f:
+            json.dump(manifest, f, indent=2)
+
+    return backup_path
+
+
+class TestDryRunRestoreSuccessful:
+    """Tests for successful dry-run restore validation."""
+
+    def test_valid_backup_passes(self, backup_dir):
+        """A well-formed backup with matching schema should pass validation."""
+        _create_backup(backup_dir, "MIG001", data_files=["data.csv"])
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG001",
+            target_schema_version="3",
+        )
+        assert result.valid is True
+        assert result.backup_present is True
+        assert result.target_compatible is True
+        assert result.schema_version == "3"
+        assert len(result.errors) == 0
+
+    def test_validation_includes_metadata(self, backup_dir):
+        """Result metadata should include migration and backup details."""
+        _create_backup(backup_dir, "MIG002", data_files=["data.csv"])
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG002",
+        )
+        assert result.metadata["migration_id"] == "MIG002"
+        assert result.metadata["from_version"] == 1
+        assert result.metadata["to_version"] == 3
+        assert result.metadata["file_count"] == 1
+
+    def test_row_counts_and_checksums_populated(self, backup_dir):
+        """Validation metadata with row counts and checksums should be surfaced."""
+        _create_backup(
+            backup_dir,
+            "MIG003",
+            manifest_extra={
+                "validation": {
+                    "row_counts": {"users": 1500, "orders": 42000},
+                    "checksums": {"users": "abc123", "orders": "def456"},
+                },
+            },
+        )
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG003",
+        )
+        assert result.valid is True
+        assert result.row_counts == {"users": 1500, "orders": 42000}
+        assert result.checksums == {"users": "abc123", "orders": "def456"}
+
+
+class TestDryRunRestoreMissingBackup:
+    """Tests for missing backup scenarios."""
+
+    def test_missing_backup_directory(self, backup_dir):
+        """A non-existent backup directory should fail with BACKUP_NOT_FOUND."""
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="NONEXISTENT",
+        )
+        assert result.valid is False
+        assert result.backup_present is False
+        assert any(e["code"] == "BACKUP_NOT_FOUND" for e in result.errors)
+
+    def test_missing_manifest(self, backup_dir):
+        """A backup directory without a manifest should fail with MANIFEST_MISSING."""
+        # Create the backup directory but not the manifest
+        backup_path = Path(backup_dir) / "migration_MIG004"
+        backup_path.mkdir(parents=True, exist_ok=True)
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG004",
+        )
+        assert result.valid is False
+        assert any(e["code"] == "MANIFEST_MISSING" for e in result.errors)
+
+    def test_invalid_manifest_json(self, backup_dir):
+        """A manifest with invalid JSON should fail with MANIFEST_INVALID."""
+        backup_path = Path(backup_dir) / "migration_MIG005"
+        backup_path.mkdir(parents=True, exist_ok=True)
+        with open(backup_path / "manifest.json", "w", encoding="utf-8") as f:
+            f.write("{invalid json!!!")
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG005",
+        )
+        assert result.valid is False
+        assert any(e["code"] == "MANIFEST_INVALID" for e in result.errors)
+
+
+class TestDryRunRestoreSchemaMismatch:
+    """Tests for schema compatibility issues."""
+
+    def test_schema_version_mismatch(self, backup_dir):
+        """Backup and target schema versions that differ should fail with SCHEMA_MISMATCH."""
+        _create_backup(backup_dir, "MIG006")
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG006",
+            target_schema_version="5",  # backup has to_version=3
+        )
+        assert result.valid is False
+        assert result.target_compatible is False
+        assert any(e["code"] == "SCHEMA_MISMATCH" for e in result.errors)
+
+    def test_no_schema_version_in_manifest(self, backup_dir):
+        """Missing schema version in manifest should fail with SCHEMA_UNKNOWN when target is specified."""
+        _create_backup(backup_dir, "MIG007", manifest_extra={"to_version": None})
+        # Remove to_version key entirely
+        backup_path = Path(backup_dir) / "migration_MIG007"
+        manifest_file = backup_path / "manifest.json"
+        with open(manifest_file, "r", encoding="utf-8") as f:
+            manifest = json.load(f)
+        del manifest["to_version"]
+        with open(manifest_file, "w", encoding="utf-8") as f:
+            json.dump(manifest, f, indent=2)
+
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG007",
+            target_schema_version="3",
+        )
+        assert result.valid is False
+        assert result.target_compatible is False
+        assert any(e["code"] == "SCHEMA_UNKNOWN" for e in result.errors)
+
+    def test_unsupported_schema_version(self, backup_dir):
+        """An unsupported schema version should fail with SCHEMA_UNSUPPORTED."""
+        _create_backup(backup_dir, "MIG008", manifest_extra={"to_version": 99})
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG008",
+            target_schema_version="99",
+        )
+        assert result.valid is False
+        assert result.target_compatible is False
+        assert any(e["code"] == "SCHEMA_UNSUPPORTED" for e in result.errors)
+
+    def test_no_target_schema_skips_compatibility(self, backup_dir):
+        """When no target_schema_version is given, compatibility check is skipped."""
+        _create_backup(backup_dir, "MIG009")
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG009",
+            target_schema_version=None,
+        )
+        assert result.valid is True
+        assert result.target_compatible is True  # defaults to True when not checked
+
+
+class TestDryRunRestoreMissingDataFiles:
+    """Tests for missing data files referenced in manifest."""
+
+    def test_missing_data_files(self, backup_dir):
+        """Referenced data files that don't exist should fail with DATA_FILES_MISSING."""
+        # Create backup with file references but don't create the actual files
+        backup_path = Path(backup_dir) / "migration_MIG010"
+        backup_path.mkdir(parents=True, exist_ok=True)
+        manifest = {
+            "migration_id": "MIG010",
+            "created_at": "2024-06-01T12:00:00Z",
+            "from_version": 1,
+            "to_version": 3,
+            "script_version": "3.2.0-legacy",
+            "files": [{"path": "users.csv"}, {"path": "orders.csv"}],
+        }
+        with open(backup_path / "manifest.json", "w", encoding="utf-8") as f:
+            json.dump(manifest, f, indent=2)
+
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG010",
+        )
+        assert result.valid is False
+        assert any(e["code"] == "DATA_FILES_MISSING" for e in result.errors)
+
+    def test_no_validation_metadata_warns(self, backup_dir):
+        """Absence of validation metadata should produce warnings but not errors."""
+        _create_backup(backup_dir, "MIG011", data_files=["data.csv"])
+        result = dry_run_restore_validation(
+            backup_dir=backup_dir,
+            migration_id="MIG011",
+        )
+        assert result.valid is True
+        assert any("No validation metadata" in w for w in result.warnings)