roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/sync/sync_checkpoint.py

@@ -0,0 +1,348 @@
+"""Checkpoint-based error recovery for sync operations.
+
+This module provides checkpoint/rollback capabilities to enable resuming
+from failures and rolling back partial syncs.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from structlog import get_logger
+
+if TYPE_CHECKING:
+    from roadmap.core.domain.issue import Issue
+    from roadmap.infrastructure.coordination.core import RoadmapCore
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class SyncCheckpoint:
+    """Represents a sync checkpoint that can be used for rollback/resume."""
+
+    checkpoint_id: str
+    timestamp: str
+    phase: str  # "fetch", "push", "baseline_update", "complete"
+    baseline_state: dict[str, dict]  # issue_id -> issue_dict
+    modified_issues: list[str]  # List of issue IDs modified during sync
+    github_operations: list[dict]  # List of GitHub operations performed
+    metadata: dict  # Additional metadata about the checkpoint
+
+
+class SyncCheckpointManager:
+    """Manages sync checkpoints for error recovery."""
+
+    def __init__(self, core: RoadmapCore):
+        """Initialize checkpoint manager.
+
+        Args:
+            core: RoadmapCore instance for state management
+        """
+        self.core = core
+        self.state_manager = core.db
+        self._current_checkpoint: SyncCheckpoint | None = None
+
+    def create_checkpoint(
+        self,
+        phase: str,
+        issues: list[Issue],
+        github_operations: list[dict] | None = None,
+        metadata: dict | None = None,
+    ) -> SyncCheckpoint:
+        """Create a checkpoint before a sync operation.
+
+        Args:
+            phase: Current phase ("fetch", "push", "baseline_update")
+            issues: List of issues to checkpoint
+            github_operations: List of GitHub operations performed so far
+            metadata: Additional checkpoint metadata
+
+        Returns:
+            SyncCheckpoint object
+        """
+        logger.info(
+            "checkpoint_created",
+            phase=phase,
+            issue_count=len(issues),
+            action="create_checkpoint",
+        )
+
+        # Generate checkpoint ID from timestamp + phase
+        timestamp = datetime.now(UTC).isoformat()
+        checkpoint_data = f"{timestamp}-{phase}"
+        checkpoint_id = hashlib.sha256(checkpoint_data.encode()).hexdigest()[:16]
+
+        # Serialize baseline state
+        baseline_state = {}
+        modified_issues = []
+        for issue in issues:
+            baseline_state[issue.id] = self._serialize_issue(issue)
+            if self._is_modified(issue):
+                modified_issues.append(issue.id)
+
+        checkpoint = SyncCheckpoint(
+            checkpoint_id=checkpoint_id,
+            timestamp=timestamp,
+            phase=phase,
+            baseline_state=baseline_state,
+            modified_issues=modified_issues,
+            github_operations=github_operations or [],
+            metadata=metadata or {},
+        )
+
+        # Save checkpoint to database
+        self._save_checkpoint(checkpoint)
+        self._current_checkpoint = checkpoint
+
+        return checkpoint
+
+    def _serialize_issue(self, issue: Issue) -> dict:
+        """Serialize an issue to a dictionary for checkpointing."""
+        issue_dict = asdict(issue)
+        # Convert datetime objects to ISO strings
+        for key, value in issue_dict.items():
+            if isinstance(value, datetime):
+                issue_dict[key] = value.isoformat()
+        return issue_dict
+
+    def _is_modified(self, issue: Issue) -> bool:
+        """Check if an issue has been modified locally."""
+        # Check if issue has local changes that haven't been synced
+        return bool(
+            getattr(issue, "_modified", False) or getattr(issue, "_local_changes", None)
+        )
+
+    def _save_checkpoint(self, checkpoint: SyncCheckpoint) -> None:
+        """Save checkpoint to database."""
+        checkpoint_key = f"sync_checkpoint_{checkpoint.checkpoint_id}"
+        checkpoint_data = {
+            "checkpoint_id": checkpoint.checkpoint_id,
+            "timestamp": checkpoint.timestamp,
+            "phase": checkpoint.phase,
+            "baseline_state": checkpoint.baseline_state,
+            "modified_issues": checkpoint.modified_issues,
+            "github_operations": checkpoint.github_operations,
+            "metadata": checkpoint.metadata,
+        }
+
+        # Store in sync_state table
+        checkpoint_key = f"checkpoint_{checkpoint.checkpoint_id}"
+        self.state_manager.save_sync_checkpoint(checkpoint_key, checkpoint_data)
+
+        # Also save as "latest_checkpoint" for easy recovery
+        self.state_manager.save_sync_checkpoint("latest_checkpoint", checkpoint_data)
+
+        logger.debug(
+            "checkpoint_saved",
+            checkpoint_id=checkpoint.checkpoint_id,
+            phase=checkpoint.phase,
+            action="save_checkpoint",
+        )
+
+    def get_latest_checkpoint(self) -> SyncCheckpoint | None:
+        """Retrieve the latest checkpoint for resuming sync.
+
+        Returns:
+            SyncCheckpoint if found, None otherwise
+        """
+        try:
+            checkpoint_data = self.state_manager.get_sync_checkpoint(
+                "latest_checkpoint"
+            )
+            if not checkpoint_data:
+                return None
+
+            return SyncCheckpoint(**checkpoint_data)
+
+        except Exception as e:
+            logger.warning(
+                "checkpoint_retrieval_failed",
+                error=str(e),
+                action="get_latest_checkpoint",
+            )
+            return None
+
+    def rollback_to_checkpoint(self, checkpoint: SyncCheckpoint) -> bool:
+        """Rollback sync to a previous checkpoint.
+
+        This will:
+        1. Restore all issues to their checkpointed state
+        2. Undo any GitHub operations if possible
+        3. Clear modified flags
+
+        Args:
+            checkpoint: Checkpoint to rollback to
+
+        Returns:
+            True if rollback successful, False otherwise
+        """
+        logger.info(
+            "checkpoint_rollback_started",
+            checkpoint_id=checkpoint.checkpoint_id,
+            phase=checkpoint.phase,
+            action="rollback_to_checkpoint",
+        )
+
+        try:
+            # Restore all issues from checkpoint
+            for issue_id, issue_data in checkpoint.baseline_state.items():
+                try:
+                    # Get current issue
+                    issue = self.core.issues.get(issue_id)
+                    if not issue:
+                        logger.warning(
+                            "checkpoint_issue_not_found",
+                            issue_id=issue_id,
+                            action="rollback_issue",
+                        )
+                        continue
+
+                    # Restore fields from checkpoint
+                    for field, value in issue_data.items():
+                        if hasattr(issue, field):
+                            setattr(issue, field, value)
+
+                    # Clear modification flags
+                    if hasattr(issue, "_modified"):
+                        issue._modified = False
+                    if hasattr(issue, "_local_changes"):
+                        issue._local_changes = None
+
+                    # Save restored issue
+                    self.core.issues.update(
+                        issue.id,
+                        **{k: v for k, v in issue_data.items() if hasattr(issue, k)},
+                    )
+
+                    logger.debug(
+                        "checkpoint_issue_restored",
+                        issue_id=issue_id,
+                        action="rollback_issue",
+                    )
+
+                except Exception as e:
+                    logger.error(
+                        "checkpoint_issue_rollback_failed",
+                        issue_id=issue_id,
+                        error=str(e),
+                        action="rollback_issue",
+                    )
+                    # Continue with other issues
+
+            # Clear the checkpoint after successful rollback
+            self.clear_checkpoint(checkpoint.checkpoint_id)
+
+            logger.info(
+                "checkpoint_rollback_completed",
+                checkpoint_id=checkpoint.checkpoint_id,
+                issues_restored=len(checkpoint.baseline_state),
+                action="rollback_to_checkpoint",
+            )
+
+            return True
+
+        except Exception as e:
+            logger.error(
+                "checkpoint_rollback_failed",
+                checkpoint_id=checkpoint.checkpoint_id,
+                error=str(e),
+                action="rollback_to_checkpoint",
+            )
+            return False
+
+    def can_resume(self) -> tuple[bool, SyncCheckpoint | None]:
+        """Check if there's a checkpoint that can be resumed.
+
+        Returns:
+            Tuple of (can_resume: bool, checkpoint: SyncCheckpoint | None)
+        """
+        checkpoint = self.get_latest_checkpoint()
+        if not checkpoint:
+            return False, None
+
+        # Check if checkpoint is recent (within last hour)
+        try:
+            checkpoint_time = datetime.fromisoformat(checkpoint.timestamp)
+            if checkpoint_time.tzinfo is None:
+                checkpoint_time = checkpoint_time.replace(tzinfo=UTC)
+            else:
+                checkpoint_time = checkpoint_time.astimezone(UTC)
+
+            time_diff = datetime.now(UTC) - checkpoint_time
+            is_recent = time_diff.total_seconds() < 3600  # 1 hour
+
+            if not is_recent:
+                logger.info(
+                    "checkpoint_too_old",
+                    checkpoint_id=checkpoint.checkpoint_id,
+                    age_seconds=time_diff.total_seconds(),
+                    action="can_resume",
+                )
+                return False, checkpoint
+
+            # Check if checkpoint is in a resumable phase
+            resumable_phases = ["fetch", "push"]
+            if checkpoint.phase not in resumable_phases:
+                logger.info(
+                    "checkpoint_phase_not_resumable",
+                    checkpoint_id=checkpoint.checkpoint_id,
+                    phase=checkpoint.phase,
+                    action="can_resume",
+                )
+                return False, checkpoint
+
+            return True, checkpoint
+
+        except Exception as e:
+            logger.warning(
+                "checkpoint_resume_check_failed",
+                error=str(e),
+                action="can_resume",
+            )
+            return False, None
+
+    def clear_checkpoint(self, checkpoint_id: str) -> None:
+        """Clear a checkpoint from storage.
+
+        Args:
+            checkpoint_id: ID of checkpoint to clear
+        """
+        checkpoint_key = f"sync_checkpoint_{checkpoint_id}"
+        try:
+            self.state_manager.delete_sync_checkpoint(checkpoint_key)
+            # Also clear latest_checkpoint if it matches
+            latest_data = self.state_manager.get_sync_checkpoint("latest_checkpoint")
+            if latest_data:
+                if latest_data.get("checkpoint_id") == checkpoint_id:
+                    self.state_manager.delete_sync_checkpoint("latest_checkpoint")
+
+            logger.debug(
+                "checkpoint_cleared",
+                checkpoint_id=checkpoint_id,
+                action="clear_checkpoint",
+            )
+        except Exception as e:
+            logger.warning(
+                "checkpoint_clear_failed",
+                checkpoint_id=checkpoint_id,
+                error=str(e),
+                action="clear_checkpoint",
+            )
+
+    def clear_all_checkpoints(self) -> None:
+        """Clear all sync checkpoints."""
+        try:
+            # Note: This is a simplified approach - in production you'd want
+            # proper enumeration of checkpoint keys
+            self.state_manager.delete_sync_checkpoint("latest_checkpoint")
+            logger.info("all_checkpoints_cleared", action="clear_all_checkpoints")
+        except Exception as e:
+            logger.warning(
+                "checkpoint_clear_all_failed",
+                error=str(e),
+                action="clear_all_checkpoints",
+            )

roadmap/core/services/sync/sync_conflict_detector.py

@@ -0,0 +1,147 @@
+"""Field-level conflict detection helpers.
+
+Extracted from SyncStateComparator._detect_field_conflicts to allow focused
+testing and reuse.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+
+import structlog
+
+from roadmap.core.services.sync.sync_conflict_resolver import ConflictField
+
+logger = structlog.get_logger()
+
+
+def _convert_enum_field(field_name: str, value: Any) -> Any:
+    """Convert string enum values to enum types for status/priority fields.
+
+    Args:
+        field_name: Name of field ("status", "priority", etc.)
+        value: Value to potentially convert
+
+    Returns:
+        Converted enum value, or original value if conversion fails/not applicable
+    """
+    if not isinstance(value, str) or value is None:
+        return value
+
+    if field_name == "status":
+        try:
+            from roadmap.common.constants import Status
+
+            try:
+                return Status(value)
+            except (ValueError, KeyError):
+                return Status(value.lower())
+        except Exception as e:
+            logger.debug(
+                "enum_conversion_failed",
+                operation="convert_enum_field",
+                field="status",
+                provided_value=value,
+                error=str(e),
+                action="Using fallback value",
+            )
+            return value
+
+    if field_name == "priority":
+        try:
+            from roadmap.common.constants import Priority
+
+            try:
+                return Priority(value)
+            except (ValueError, KeyError):
+                return Priority(value.lower())
+        except Exception as e:
+            logger.debug(
+                "enum_conversion_failed",
+                operation="convert_enum_field",
+                field="priority",
+                provided_value=value,
+                error=str(e),
+                action="Using fallback value",
+            )
+            return value
+
+    return value
+
+
+def _get_field_value(obj: dict[str, Any] | object, field_name: str) -> Any:
+    """Safely extract field value from dict or object."""
+    if isinstance(obj, dict):
+        return obj.get(field_name)
+    return getattr(obj, field_name, None)
+
+
+def detect_field_conflicts(
+    local: object,
+    remote: dict[str, Any] | object,
+    fields_to_sync: list[str],
+    extract_timestamp: Callable[[object, str], datetime | None] | None = None,
+    logger: Any | None = None,
+) -> list[ConflictField]:
+    """Detect field-level conflicts between local and remote issues.
+
+    Args:
+        local: local Issue-like object
+        remote: remote dict or object
+        fields_to_sync: list of field names to compare
+        extract_timestamp: optional callable to extract timestamps from remote
+        logger: optional logger for debug/info
+
+    Returns:
+        list of ConflictField
+    """
+    conflicts: list[ConflictField] = []
+
+    for field_name in fields_to_sync:
+        try:
+            local_val = getattr(local, field_name, None)
+            remote_val = _get_field_value(remote, field_name)
+
+            # Convert enum strings to types
+            remote_val = _convert_enum_field(field_name, remote_val)
+
+            if not local_val and not remote_val:
+                continue
+
+            if local_val != remote_val:
+                local_updated = getattr(local, "updated", None)
+                remote_updated: datetime | None = None
+                if extract_timestamp is not None:
+                    try:
+                        remote_updated = extract_timestamp(remote, "updated_at")
+                    except Exception:
+                        remote_updated = None
+
+                conflict_field = ConflictField(
+                    field_name=field_name,
+                    local_value=local_val,
+                    remote_value=remote_val,
+                    local_updated=local_updated,
+                    remote_updated=remote_updated,
+                )
+                conflicts.append(conflict_field)
+
+        except Exception as e:
+            if logger is not None:
+                try:
+                    logger.debug(
+                        "field_conflict_check_error",
+                        field=field_name,
+                        error=str(e),
+                    )
+                except Exception as logging_error:
+                    logger.error(
+                        "logger_failed",
+                        operation="log_field_conflict_error",
+                        error=str(logging_error),
+                    )
+            continue
+
+    return conflicts