Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(workspace): retain corrupt migration journals as recovery blockers

Bingxi Zhao (Frank)844c8f0a22aa
diff --git a/deeptutor/services/workspace/data_migration.py b/deeptutor/services/workspace/data_migration.py
index 1cdd7dd80..1ca42a2bb 100644
--- a/deeptutor/services/workspace/data_migration.py
+++ b/deeptutor/services/workspace/data_migration.py
@@ -898,6 +898,42 @@ def _restore_sessions(root: Path, source, target) -> None:
Path(str(target.get_chat_history_db()) + suffix).unlink(missing_ok=True)
+def _read_journal(path: Path) -> dict:
+ """Validate recovery control data before it can authorize filesystem changes."""
+ row = json.loads(path.read_text())
+ terminal = {"completed", "exported", "recovered"}
+ pending = {
+ "preparing",
+ "copying",
+ "transferring",
+ "committed",
+ "cleanup_required",
+ "recovery_required",
+ }
+ if not isinstance(row, dict) or row.get("id") != path.parent.name:
+ raise ValueError("journal identity is missing or invalid")
+ status = row.get("status")
+ if not isinstance(status, str) or status not in terminal | pending | {"failed"}:
+ raise ValueError("journal status is missing or invalid")
+ if not isinstance(row.get("created_at", ""), str):
+ raise ValueError("journal timestamp is invalid")
+ if status not in terminal:
+ plan = row.get("plan")
+ if not isinstance(plan, dict) or any(
+ not isinstance(plan.get(key), str)
+ for key in ("source_workspace_id", "target_workspace_id")
+ ):
+ raise ValueError("journal recovery plan is missing or invalid")
+ features = plan.get("features")
+ if (
+ not isinstance(features, list)
+ or not features
+ or any(not isinstance(feature, str) or feature not in FEATURES for feature in features)
+ ):
+ raise ValueError("journal recovery features are missing or invalid")
+ return row
+
+
def _journal_rows() -> list[tuple[Path, dict | None]]:
"""Read every migration journal. Corrupt entries yield ``(path, None)``.
@@ -909,9 +945,7 @@ def _journal_rows() -> list[tuple[Path, dict | None]]:
rows: list[tuple[Path, dict | None]] = []
for path in _journal_root().glob("*/operation.json"):
try:
- row = json.loads(path.read_text())
- if not isinstance(row, dict):
- raise ValueError("journal is not a JSON object")
+ row = _read_journal(path)
except (OSError, ValueError):
row = None
rows.append((path, row))
@@ -963,8 +997,8 @@ def assert_no_pending_recovery(*, reject_unreadable: bool = False) -> None:
if reject_unreadable:
raise WorkspaceError(
"A migration journal is unreadable, so a pending recovery cannot be "
- f"ruled out: {path}. Use Recover migration in Settings → Data migration to "
- "quarantine it before changing learning data."
+ f"ruled out: {path}. Automatic recovery is unavailable; preserve the "
+ "journal and snapshots for manual repair before migrating data."
)
continue
if row.get("status") in pending:
@@ -983,23 +1017,15 @@ def recover_operation(operation_id: str) -> dict:
raise WorkspaceError("Migration not found.")
with data_activity(exclusive=True):
try:
- result = json.loads(journal.read_text())
- if not isinstance(result, dict):
- raise ValueError("journal is not a JSON object")
+ result = _read_journal(journal)
except (OSError, ValueError) as exc:
- # The plan and status are unrecoverable, so finish- or
- # rollback-recovery is impossible. Quarantine the journal (the
- # snapshots stay for inspection) so prechecks pass again.
- quarantine = root / "operation.json.corrupt"
- quarantine.unlink(missing_ok=True)
- journal.rename(quarantine)
- logger.warning("Quarantined unreadable migration journal %s: %s", journal, exc)
- return {
- "id": operation_id,
- "status": "recovered",
- "created_at": datetime.now(timezone.utc).isoformat(),
- "recovery_path": str(root),
- }
+ # Neither rollback nor cleanup is safe without the original plan.
+ # Keep the journal discoverable so subsequent migrations stay blocked.
+ logger.warning("Cannot automatically recover unreadable migration journal %s", journal)
+ raise WorkspaceError(
+ f"Migration journal is unreadable: {journal}. Automatic recovery is "
+ "unavailable; the journal and snapshots have been preserved for manual repair."
+ ) from exc
if result["status"] in {"completed", "exported", "recovered"}:
return result
plan = result["plan"]
diff --git a/tests/services/workspace/test_data_migration.py b/tests/services/workspace/test_data_migration.py
index 4a466f204..01c9d0cc1 100644
--- a/tests/services/workspace/test_data_migration.py
+++ b/tests/services/workspace/test_data_migration.py
@@ -264,11 +264,19 @@ def test_unreadable_journal_blocks_only_migration_paths(account):
assert_no_pending_recovery(reject_unreadable=True)
with pytest.raises(WorkspaceError, match=re.escape(str(corrupt_journal))):
migrate_data("", account.create_workspace("Destination")["workspace_id"], ["chat"])
- # The settings recover entry quarantines the journal, not a 500.
- assert recover_operation(corrupt_id)["status"] == "recovered"
- assert not corrupt_journal.exists()
- assert (corrupt_dir / "operation.json.corrupt").is_file()
- assert_no_pending_recovery(reject_unreadable=True)
+ snapshot = corrupt_dir / "snapshot" / "chat.db"
+ snapshot.parent.mkdir()
+ snapshot.write_bytes(b"preserve this recovery copy")
+ # Failed recovery must not hide the blocker or overwrite recovery evidence.
+ for _ in range(2):
+ with pytest.raises(WorkspaceError, match="preserved for manual repair"):
+ recover_operation(corrupt_id)
+ assert corrupt_journal.read_text() == "{ truncated journal"
+ assert snapshot.read_bytes() == b"preserve this recovery copy"
+ assert not (corrupt_dir / "operation.json.corrupt").exists()
+ with pytest.raises(WorkspaceError, match="manual repair"):
+ assert_no_pending_recovery(reject_unreadable=True)
+ assert_no_pending_recovery()
def test_crash_during_copy_tracks_partial_destination(account, monkeypatch):
@@ -565,3 +573,38 @@ def test_migration_preview_returns_skip_warnings(account):
plan = preview("", target, ["book"])
assert "warnings" in plan
assert any("book_corrupt/manifest.json" in message for message in plan["warnings"])
+
+
+ "payload",
+ [
+ "{}",
+ "[]",
+ '{"status":"completed"}',
+ '{"id":"ID","status":"unknown"}',
+ '{"id":"ID","status":"copying","plan":{}}',
+ '{"id":"ID","status":[]}',
+ ],
+)
+def test_structurally_invalid_journal_requires_manual_repair(account, payload):
+ from deeptutor.services.workspace.data_migration import (
+ _journal_root,
+ assert_no_pending_recovery,
+ operations,
+ recover_operation,
+ )
+
+ operation_id = "a" * 32
+ root = _journal_root() / operation_id
+ root.mkdir()
+ journal = root / "operation.json"
+ content = payload.replace("ID", operation_id)
+ journal.write_text(content)
+
+ assert operations()[0]["status"] == "unreadable"
+ assert_no_pending_recovery()
+ with pytest.raises(WorkspaceError, match="manual repair"):
+ assert_no_pending_recovery(reject_unreadable=True)
+ with pytest.raises(WorkspaceError, match="manual repair"):
+ recover_operation(operation_id)
+ assert journal.read_text() == content