dory-sdk 2.1.0__py3-none-any.whl → 2.1.4__py3-none-any.whl

dory/migration/versioning.py

@@ -0,0 +1,749 @@
+"""State format version negotiation.
+
+Provides version-aware serialization and deserialization to ensure
+compatibility between different versions of the SDK and Orchestrator.
+
+Format Versions:
+    v1.0 - Original SDK format (StateEnvelope with payload/metadata/checksum)
+    v2.0 - Orchestrator-compatible format (ApplicationState structure)
+
+The SDK supports reading both formats and can write in either format
+depending on the target version.
+"""
+
+import hashlib
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+
+from dory.utils.errors import DoryStateError
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Version Constants
+# =============================================================================
+
+class StateFormatVersion(Enum):
+    """State format versions."""
+
+    V1_0 = "1.0"  # Original SDK format (StateEnvelope)
+    V2_0 = "2.0"  # Orchestrator-compatible format (ApplicationState)
+
+    @classmethod
+    def latest(cls) -> "StateFormatVersion":
+        """Get the latest format version."""
+        return cls.V2_0
+
+    @classmethod
+    def from_string(cls, version: str) -> "StateFormatVersion":
+        """Parse version string.
+
+        Args:
+            version: Version string like "1.0" or "2.0"
+
+        Returns:
+            StateFormatVersion enum
+
+        Raises:
+            ValueError: If version is not recognized
+        """
+        # Handle various formats
+        version = version.strip().lstrip("v")
+
+        for v in cls:
+            if v.value == version:
+                return v
+
+        raise ValueError(f"Unknown state format version: {version}")
+
+    def is_compatible_with(self, other: "StateFormatVersion") -> bool:
+        """Check if this version can read data from another version."""
+        # V2.0 can read V1.0 (backward compatible)
+        # V1.0 cannot read V2.0 (forward incompatible)
+        if self == StateFormatVersion.V2_0:
+            return True  # V2 can read all versions
+        elif self == StateFormatVersion.V1_0:
+            return other == StateFormatVersion.V1_0
+        return False
+
+
+# Current SDK version
+SDK_STATE_VERSION = StateFormatVersion.V2_0
+
+# Minimum supported version for reading
+MIN_SUPPORTED_VERSION = StateFormatVersion.V1_0
+
+
+# =============================================================================
+# State Structures
+# =============================================================================
+
+@dataclass
+class StateMetadata:
+    """Metadata accompanying state data."""
+
+    # Timing
+    timestamp: float = field(default_factory=time.time)
+    timestamp_iso: str = ""
+
+    # Identity
+    processor_id: str = ""
+    pod_name: str = ""
+    app_name: str = ""
+
+    # Runtime info
+    restart_count: int = 0
+    uptime_seconds: float = 0.0
+    request_count: int = 0
+
+    # Version info
+    format_version: str = SDK_STATE_VERSION.value
+    sdk_version: str = ""
+
+    def __post_init__(self):
+        """Set derived fields."""
+        if not self.timestamp_iso:
+            self.timestamp_iso = time.strftime(
+                "%Y-%m-%dT%H:%M:%SZ",
+                time.gmtime(self.timestamp)
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "timestamp": self.timestamp,
+            "timestamp_iso": self.timestamp_iso,
+            "processor_id": self.processor_id,
+            "pod_name": self.pod_name,
+            "app_name": self.app_name,
+            "restart_count": self.restart_count,
+            "uptime_seconds": self.uptime_seconds,
+            "request_count": self.request_count,
+            "format_version": self.format_version,
+            "sdk_version": self.sdk_version,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "StateMetadata":
+        """Create from dictionary."""
+        return cls(
+            timestamp=data.get("timestamp", time.time()),
+            timestamp_iso=data.get("timestamp_iso", ""),
+            processor_id=data.get("processor_id", ""),
+            pod_name=data.get("pod_name", ""),
+            app_name=data.get("app_name", ""),
+            restart_count=data.get("restart_count", 0),
+            uptime_seconds=data.get("uptime_seconds", 0.0),
+            request_count=data.get("request_count", 0),
+            format_version=data.get("format_version", SDK_STATE_VERSION.value),
+            sdk_version=data.get("sdk_version", ""),
+        )
+
+
+@dataclass
+class VersionedState:
+    """Version-aware state container.
+
+    This is the canonical internal representation that can be
+    serialized to any supported format version.
+    """
+
+    # Core data
+    data: dict[str, Any]
+    metadata: StateMetadata
+
+    # Integrity
+    checksum: str = ""
+
+    # Optional fields (for Orchestrator compatibility)
+    metrics: dict[str, float] = field(default_factory=dict)
+    connections: list[str] = field(default_factory=list)
+    active_sessions: int = 0
+    session_data: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Compute checksum if not provided."""
+        if not self.checksum:
+            self.checksum = self._compute_checksum()
+
+    def _compute_checksum(self) -> str:
+        """Compute SHA256 checksum of data."""
+        data_json = json.dumps(self.data, sort_keys=True)
+        return hashlib.sha256(data_json.encode()).hexdigest()
+
+    def validate_checksum(self) -> bool:
+        """Validate that checksum matches data."""
+        expected = self._compute_checksum()
+        return self.checksum == expected
+
+    @property
+    def format_version(self) -> StateFormatVersion:
+        """Get format version."""
+        return StateFormatVersion.from_string(self.metadata.format_version)
+
+
+# =============================================================================
+# Version Detection
+# =============================================================================
+
+def detect_format_version(data: dict[str, Any]) -> StateFormatVersion:
+    """Detect the format version of serialized state.
+
+    Args:
+        data: Parsed JSON state data
+
+    Returns:
+        Detected StateFormatVersion
+    """
+    # Check for explicit version field
+    if "state_version" in data:
+        # Orchestrator V2 format
+        try:
+            return StateFormatVersion.from_string(data["state_version"])
+        except ValueError:
+            pass
+
+    if "format_version" in data.get("metadata", {}):
+        # SDK format with version in metadata
+        try:
+            return StateFormatVersion.from_string(data["metadata"]["format_version"])
+        except ValueError:
+            pass
+
+    # Check structure to detect format
+    if "payload" in data and "metadata" in data and "checksum" in data:
+        # V1.0 SDK format (StateEnvelope)
+        return StateFormatVersion.V1_0
+
+    if "data" in data and ("pod_name" in data or "app_name" in data):
+        # V2.0 Orchestrator format (ApplicationState)
+        return StateFormatVersion.V2_0
+
+    # Default to V1.0 for backward compatibility
+    logger.warning("Could not detect state format version, assuming V1.0")
+    return StateFormatVersion.V1_0
+
+
+# =============================================================================
+# Serializers
+# =============================================================================
+
+class StateSerializerV1:
+    """Serializer for V1.0 format (original SDK StateEnvelope)."""
+
+    @staticmethod
+    def serialize(state: VersionedState) -> str:
+        """Serialize to V1.0 format.
+
+        Args:
+            state: VersionedState to serialize
+
+        Returns:
+            JSON string in V1.0 format
+        """
+        envelope = {
+            "payload": state.data,
+            "metadata": {
+                "timestamp": state.metadata.timestamp,
+                "timestamp_iso": state.metadata.timestamp_iso,
+                "processor_id": state.metadata.processor_id,
+                "pod_name": state.metadata.pod_name,
+                "restart_count": state.metadata.restart_count,
+            },
+            "checksum": state.checksum,
+        }
+        return json.dumps(envelope, indent=2)
+
+    @staticmethod
+    def deserialize(data: str) -> VersionedState:
+        """Deserialize from V1.0 format.
+
+        Args:
+            data: JSON string in V1.0 format
+
+        Returns:
+            VersionedState
+
+        Raises:
+            DoryStateError: If deserialization fails
+        """
+        try:
+            envelope = json.loads(data)
+        except json.JSONDecodeError as e:
+            raise DoryStateError(f"Invalid JSON: {e}", cause=e)
+
+        if "payload" not in envelope:
+            raise DoryStateError("Missing 'payload' field in V1.0 state")
+
+        metadata_dict = envelope.get("metadata", {})
+        metadata = StateMetadata(
+            timestamp=metadata_dict.get("timestamp", time.time()),
+            timestamp_iso=metadata_dict.get("timestamp_iso", ""),
+            processor_id=metadata_dict.get("processor_id", ""),
+            pod_name=metadata_dict.get("pod_name", ""),
+            restart_count=metadata_dict.get("restart_count", 0),
+            format_version=StateFormatVersion.V1_0.value,
+        )
+
+        return VersionedState(
+            data=envelope["payload"],
+            metadata=metadata,
+            checksum=envelope.get("checksum", ""),
+        )
+
+
+class StateSerializerV2:
+    """Serializer for V2.0 format (Orchestrator ApplicationState)."""
+
+    @staticmethod
+    def serialize(state: VersionedState) -> str:
+        """Serialize to V2.0 format (Orchestrator-compatible).
+
+        Args:
+            state: VersionedState to serialize
+
+        Returns:
+            JSON string in V2.0 format
+        """
+        app_state = {
+            # Metadata
+            "pod_name": state.metadata.pod_name,
+            "app_name": state.metadata.app_name or state.metadata.processor_id,
+            "captured_at": state.metadata.timestamp_iso,
+            "state_version": StateFormatVersion.V2_0.value,
+
+            # Application data
+            "data": state.data,
+            "metrics": state.metrics,
+            "connections": state.connections,
+
+            # Session info
+            "active_sessions": state.active_sessions,
+            "session_data": state.session_data,
+
+            # Runtime
+            "uptime_seconds": state.metadata.uptime_seconds,
+            "request_count": state.metadata.request_count,
+            "last_health_time": state.metadata.timestamp_iso,
+
+            # SDK-specific (for round-trip compatibility)
+            "_sdk_metadata": {
+                "processor_id": state.metadata.processor_id,
+                "restart_count": state.metadata.restart_count,
+                "checksum": state.checksum,
+                "format_version": StateFormatVersion.V2_0.value,
+                "sdk_version": state.metadata.sdk_version,
+            },
+        }
+        return json.dumps(app_state, indent=2)
+
+    @staticmethod
+    def deserialize(data: str) -> VersionedState:
+        """Deserialize from V2.0 format.
+
+        Args:
+            data: JSON string in V2.0 format
+
+        Returns:
+            VersionedState
+
+        Raises:
+            DoryStateError: If deserialization fails
+        """
+        try:
+            app_state = json.loads(data)
+        except json.JSONDecodeError as e:
+            raise DoryStateError(f"Invalid JSON: {e}", cause=e)
+
+        # Extract SDK metadata if present
+        sdk_metadata = app_state.get("_sdk_metadata", {})
+
+        # Parse captured_at timestamp
+        timestamp = time.time()
+        timestamp_iso = app_state.get("captured_at", "")
+        if timestamp_iso:
+            try:
+                import datetime
+                dt = datetime.datetime.fromisoformat(timestamp_iso.replace("Z", "+00:00"))
+                timestamp = dt.timestamp()
+            except (ValueError, AttributeError):
+                pass
+
+        metadata = StateMetadata(
+            timestamp=timestamp,
+            timestamp_iso=timestamp_iso,
+            processor_id=sdk_metadata.get("processor_id", app_state.get("app_name", "")),
+            pod_name=app_state.get("pod_name", ""),
+            app_name=app_state.get("app_name", ""),
+            restart_count=sdk_metadata.get("restart_count", 0),
+            uptime_seconds=app_state.get("uptime_seconds", 0.0),
+            request_count=app_state.get("request_count", 0),
+            format_version=StateFormatVersion.V2_0.value,
+            sdk_version=sdk_metadata.get("sdk_version", ""),
+        )
+
+        return VersionedState(
+            data=app_state.get("data", {}),
+            metadata=metadata,
+            checksum=sdk_metadata.get("checksum", ""),
+            metrics=app_state.get("metrics", {}),
+            connections=app_state.get("connections", []),
+            active_sessions=app_state.get("active_sessions", 0),
+            session_data=app_state.get("session_data", {}),
+        )
+
+
+# =============================================================================
+# Version Negotiation
+# =============================================================================
+
+@dataclass
+class VersionNegotiationResult:
+    """Result of version negotiation."""
+
+    agreed_version: StateFormatVersion
+    sdk_version: StateFormatVersion
+    peer_version: StateFormatVersion | None
+    is_compatible: bool
+    migration_required: bool
+    message: str
+
+
+class VersionNegotiator:
+    """Negotiates state format version between SDK and Orchestrator.
+
+    Usage:
+        negotiator = VersionNegotiator()
+
+        # Check if we can read incoming state
+        result = negotiator.negotiate_read("2.0")
+        if result.is_compatible:
+            state = negotiator.deserialize(json_data)
+
+        # Serialize for target version
+        json_data = negotiator.serialize(state, target_version="2.0")
+    """
+
+    def __init__(
+        self,
+        sdk_version: StateFormatVersion = SDK_STATE_VERSION,
+        min_version: StateFormatVersion = MIN_SUPPORTED_VERSION,
+    ):
+        """Initialize negotiator.
+
+        Args:
+            sdk_version: This SDK's state format version
+            min_version: Minimum version this SDK can read
+        """
+        self._sdk_version = sdk_version
+        self._min_version = min_version
+        self._serializers = {
+            StateFormatVersion.V1_0: StateSerializerV1(),
+            StateFormatVersion.V2_0: StateSerializerV2(),
+        }
+
+    @property
+    def sdk_version(self) -> StateFormatVersion:
+        """Get SDK's state format version."""
+        return self._sdk_version
+
+    @property
+    def supported_versions(self) -> list[StateFormatVersion]:
+        """Get list of supported versions."""
+        return list(StateFormatVersion)
+
+    def negotiate_read(
+        self,
+        peer_version: str | StateFormatVersion | None = None,
+    ) -> VersionNegotiationResult:
+        """Negotiate version for reading state from peer.
+
+        Args:
+            peer_version: Version string from peer (e.g., "1.0", "2.0")
+
+        Returns:
+            VersionNegotiationResult
+        """
+        if peer_version is None:
+            # No version info, assume we can read with SDK version
+            return VersionNegotiationResult(
+                agreed_version=self._sdk_version,
+                sdk_version=self._sdk_version,
+                peer_version=None,
+                is_compatible=True,
+                migration_required=False,
+                message="No peer version provided, using SDK version",
+            )
+
+        if isinstance(peer_version, str):
+            try:
+                peer_version = StateFormatVersion.from_string(peer_version)
+            except ValueError:
+                return VersionNegotiationResult(
+                    agreed_version=self._sdk_version,
+                    sdk_version=self._sdk_version,
+                    peer_version=None,
+                    is_compatible=False,
+                    migration_required=False,
+                    message=f"Unknown peer version: {peer_version}",
+                )
+
+        # Check compatibility
+        is_compatible = self._sdk_version.is_compatible_with(peer_version)
+        migration_required = peer_version != self._sdk_version
+
+        if is_compatible:
+            message = f"Compatible: SDK {self._sdk_version.value} can read {peer_version.value}"
+        else:
+            message = f"Incompatible: SDK {self._sdk_version.value} cannot read {peer_version.value}"
+
+        return VersionNegotiationResult(
+            agreed_version=peer_version if is_compatible else self._sdk_version,
+            sdk_version=self._sdk_version,
+            peer_version=peer_version,
+            is_compatible=is_compatible,
+            migration_required=migration_required,
+            message=message,
+        )
+
+    def negotiate_write(
+        self,
+        target_version: str | StateFormatVersion | None = None,
+    ) -> VersionNegotiationResult:
+        """Negotiate version for writing state.
+
+        Args:
+            target_version: Requested target version
+
+        Returns:
+            VersionNegotiationResult
+        """
+        if target_version is None:
+            # Use SDK's default version
+            return VersionNegotiationResult(
+                agreed_version=self._sdk_version,
+                sdk_version=self._sdk_version,
+                peer_version=None,
+                is_compatible=True,
+                migration_required=False,
+                message=f"Using SDK default version: {self._sdk_version.value}",
+            )
+
+        if isinstance(target_version, str):
+            try:
+                target_version = StateFormatVersion.from_string(target_version)
+            except ValueError:
+                return VersionNegotiationResult(
+                    agreed_version=self._sdk_version,
+                    sdk_version=self._sdk_version,
+                    peer_version=None,
+                    is_compatible=False,
+                    migration_required=False,
+                    message=f"Unknown target version: {target_version}",
+                )
+
+        # Check if we can write this version
+        can_write = target_version in self._serializers
+
+        return VersionNegotiationResult(
+            agreed_version=target_version if can_write else self._sdk_version,
+            sdk_version=self._sdk_version,
+            peer_version=target_version,
+            is_compatible=can_write,
+            migration_required=target_version != self._sdk_version,
+            message=f"{'Can' if can_write else 'Cannot'} write version {target_version.value}",
+        )
+
+    def serialize(
+        self,
+        state: VersionedState,
+        target_version: StateFormatVersion | str | None = None,
+    ) -> str:
+        """Serialize state to specified format version.
+
+        Args:
+            state: State to serialize
+            target_version: Target format version (default: SDK version)
+
+        Returns:
+            JSON string in target format
+
+        Raises:
+            DoryStateError: If serialization fails
+        """
+        if target_version is None:
+            target_version = self._sdk_version
+        elif isinstance(target_version, str):
+            target_version = StateFormatVersion.from_string(target_version)
+
+        serializer = self._serializers.get(target_version)
+        if not serializer:
+            raise DoryStateError(f"No serializer for version {target_version.value}")
+
+        return serializer.serialize(state)
+
+    def deserialize(self, data: str) -> VersionedState:
+        """Deserialize state, auto-detecting format version.
+
+        Args:
+            data: JSON string
+
+        Returns:
+            VersionedState
+
+        Raises:
+            DoryStateError: If deserialization fails
+        """
+        try:
+            parsed = json.loads(data)
+        except json.JSONDecodeError as e:
+            raise DoryStateError(f"Invalid JSON: {e}", cause=e)
+
+        version = detect_format_version(parsed)
+
+        serializer = self._serializers.get(version)
+        if not serializer:
+            raise DoryStateError(f"No deserializer for version {version.value}")
+
+        return serializer.deserialize(data)
+
+    def migrate(
+        self,
+        state: VersionedState,
+        target_version: StateFormatVersion,
+    ) -> VersionedState:
+        """Migrate state to a different format version.
+
+        This doesn't change the data, just updates the metadata
+        to indicate the new format version.
+
+        Args:
+            state: State to migrate
+            target_version: Target format version
+
+        Returns:
+            New VersionedState with updated version
+        """
+        # Create new metadata with updated version
+        new_metadata = StateMetadata(
+            timestamp=state.metadata.timestamp,
+            timestamp_iso=state.metadata.timestamp_iso,
+            processor_id=state.metadata.processor_id,
+            pod_name=state.metadata.pod_name,
+            app_name=state.metadata.app_name,
+            restart_count=state.metadata.restart_count,
+            uptime_seconds=state.metadata.uptime_seconds,
+            request_count=state.metadata.request_count,
+            format_version=target_version.value,
+            sdk_version=state.metadata.sdk_version,
+        )
+
+        return VersionedState(
+            data=state.data,
+            metadata=new_metadata,
+            checksum=state.checksum,
+            metrics=state.metrics,
+            connections=state.connections,
+            active_sessions=state.active_sessions,
+            session_data=state.session_data,
+        )
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+# Global negotiator instance
+_default_negotiator = VersionNegotiator()
+
+
+def get_sdk_version() -> str:
+    """Get SDK's state format version string."""
+    return SDK_STATE_VERSION.value
+
+
+def get_supported_versions() -> list[str]:
+    """Get list of supported version strings."""
+    return [v.value for v in StateFormatVersion]
+
+
+def is_version_supported(version: str) -> bool:
+    """Check if a version is supported."""
+    try:
+        StateFormatVersion.from_string(version)
+        return True
+    except ValueError:
+        return False
+
+
+def serialize_state(
+    data: dict[str, Any],
+    processor_id: str,
+    pod_name: str = "",
+    target_version: str | None = None,
+    **kwargs: Any,
+) -> str:
+    """Serialize state data with version negotiation.
+
+    Args:
+        data: State data dictionary
+        processor_id: Processor identifier
+        pod_name: Pod name
+        target_version: Target format version (default: latest)
+        **kwargs: Additional metadata fields
+
+    Returns:
+        JSON string in target format
+    """
+    metadata = StateMetadata(
+        processor_id=processor_id,
+        pod_name=pod_name,
+        app_name=kwargs.get("app_name", processor_id),
+        restart_count=kwargs.get("restart_count", 0),
+        uptime_seconds=kwargs.get("uptime_seconds", 0.0),
+        request_count=kwargs.get("request_count", 0),
+        sdk_version=kwargs.get("sdk_version", ""),
+    )
+
+    state = VersionedState(
+        data=data,
+        metadata=metadata,
+        metrics=kwargs.get("metrics", {}),
+        connections=kwargs.get("connections", []),
+        active_sessions=kwargs.get("active_sessions", 0),
+        session_data=kwargs.get("session_data", {}),
+    )
+
+    return _default_negotiator.serialize(state, target_version)
+
+
+def deserialize_state(data: str) -> tuple[dict[str, Any], StateMetadata]:
+    """Deserialize state data with version auto-detection.
+
+    Args:
+        data: JSON string
+
+    Returns:
+        Tuple of (state_data, metadata)
+    """
+    state = _default_negotiator.deserialize(data)
+    return state.data, state.metadata
+
+
+def get_version_info() -> dict[str, Any]:
+    """Get version information for health/status endpoints.
+
+    Returns:
+        Dictionary with version information
+    """
+    return {
+        "state_format_version": SDK_STATE_VERSION.value,
+        "supported_versions": get_supported_versions(),
+        "min_supported_version": MIN_SUPPORTED_VERSION.value,
+        "latest_version": StateFormatVersion.latest().value,
+    }